<!DOCTYPE HTML>
<html>
<head>
<title>BOOMR API</title>
<meta http-equiv="Content-type" content="text/html; charset=utf-8">
<link rel="stylesheet" type="text/css" href="../../boomerang-docs.css">
</head>
<body>
<span style="float:right;"><a href="../">ドキュメント一覧</a> | <a href="index.html">API</a></span>
<h1>BOOMR オブジェクト</h1>
<p>
boomerang は全て <code>BOOMR</code> オブジェクトを通してアクセスします。それぞれのプラグインは各 API を持っていますが、それも <code>BOOMR.plugins</code> を通した領域となります。このドキュメントは主に <code>BOOMR</code> オブジェクトについて記述します。
</p>

<p>
以下のいずれかへのアクセスには BOOMR オブジェクトを参照します。例えば <code>version</code> の文字列を取得するには、<code>BOOMR.version</code> を使います。
</p>

<h2 id="properties">プロパティ</h2>

<dl class="api">

<dt>version</dt>
<dd>
<p>
boomerang ライブラリーのバージョン。バージョンは メジャー.マイナー.パッチレベル 形式の文字列になります。標準的なバージョンナンバリングが適用されます。
</p>
</dd>

<dt>plugins</dt>
<dd>
<p>
boomerang に追加されている全てのプラグインを格納します。もしあなたが自分でプラグインをつくった場合このオブジェクトに追加するべきです:
</p>
<pre>
BOOMR.plugins.MyPlugin = {
	...
};</pre>
</dd>

</dl>

<h2 id="config">設定</h2>
<p>
boomerang の設定については <a href="../howtos/howto-6.html">使用方法 #6 &mdash; boomerang を設定する</a> に記載されています。<code>BOOMR</code> オブジェクトに関係があるパラメーターは:
</p>
<dl>
<dt>beacon_url</dt>
<dd>
<strong>[強く推奨]</strong>
ビーコンの結果を送る URL 。全てのパラメーターはこの URL の QueryString に追加されます。この URL は QueryString 部分を事前に持っておく必要はありません。このパラメーターには初期値はありません。もし設定されていなければビーコンは送信されません。
</dd>

<dt>site_domain</dt>
<dd>
<strong>[推奨]</strong>
全ての Cookie がセットされるドメイン。boomerang はこれを自動判別しようとしますが、あなたのサイトが foo.com の形式の場合を除き、実際には取得に失敗します。これはドメイン間で共有する帯域幅やパフォーマンスを測定したいときに役立ちます。もし複数のドメインを持っている場合はうまくいきません。別々に測定しなければなりません。
</dd>

<dt>user_ip</dt>
<dd>
<strong>[推奨]</strong>
この名前にもかかわらず、これはユーザーのコネクションをユニークに区別するために使われる自由な文字列です。これは主にユーザーの帯域幅を再測定するかどうかの判断に使われるか、または Cookie に格納される値に使われます。IPv4 アドレスや IPv6 アドレスまたはそれ以外のユーザーのコネクションを区別できるものを使うことになります。
</dd>

<dt>log</dt>
<dd>
<strong>[オプション]</strong>
初期値では boomerang は YUI のロガーコンポーネントが見つかればそれを、Firebug が見つかれば代わりにそれを使おうと試みます。どちらもない場合は、初期状態では何もログに残しません。ログメッセージ用の関数のために log パラメーターを設定することで自身のロガーを定義することができます。<br>
この関数については:
<pre>
function log(oMessage, sLevel, sSource);
</pre>
どこに:<dl>
<dt>oMessage</dt> <dd>記録されるオブジェクトまたはメッセージ。記録するオブジェクトを決定するだけです。<dd>
<dt>sLevel</dt> <dd>"error"、"warn"、"info"、"debug" などのログレベル。</dd>
<dt>sSource</dt> <dd>ログメッセージのソース。通常はプラグインの名前がついた "boomerang" の文字列になります。</dd>
</dl>
<code>log</code> に <code>null</code> を設定することでログの記録を無効にできます。
</dd>

<dt>autorun</dt>
<dd>
<strong>[オプション]</strong>
初期値では boomerang は自動的に実行され <code>window.onload</code> イベントに <code>page_ready</code> ハンドラーが登録されます。もし <code>autorun</code> を <code>false</code> にすると、これは起こらず、<code>BOOMR.page_ready()</code> を自分で呼び出す必要があります。
</dd>

<dt>&lt;plugin_name&gt;<dt>
<dd>
それぞれのプラグインは設定オブジェクトのサブオブジェクトを通して設定を行ないます。キーはプラグインの名前になります。ビルトインのプラグインの設定方法については次の各セクションをご覧ください。
</dd>

</dl>

<h2 id="methods">メソッド</h2>

<dl class="api">

<dt>init(oConfig)</dt>
<dd>
<p>
boomerang を初期化するために呼び出すのが init メソッドです。boomerang の JavaScript の読み込みが終わったあとにこのメソッドを一度だけ呼び出します。一つの設定オブジェクトをパラメーターとして受け取ります。詳細は <a href="#config">設定項目の説明</a> をご覧ください。
</p>
<h3>返り値</h3>
<p>
<code>BOOMR</code> オブジェクトへの参照。メソッドチェーンをサポートします。
</p>
</dd>

<dt>page_ready()</dt>
<dd>
<p>
<code>page_ready</code> イベントを発行するメソッドです。<code>init()</code> メソッドを呼び出した時に <code>autorun</code> を false にしているときだけこのメソッドを呼び出します。あなたのページではユーザーが ready を使う場合にはこのメソッドを呼び出す必要があります。これはページの読み込み時間の測定時の終了時間になります。
</p>
<h3>例:</h3>
<p>
このメソッドの使い方の例は <a href="../howtos/howto-1b-page%231.html">使用方法 #1b</a> をご覧ください。
</p>
<h3>返り値</h3>
<p>
<code>BOOMR</code> オブジェクトへの参照。メソッドチェーンをサポートします。
</p>
</dd>

<dt>subscribe(sEvent, fCallbackFn, oCallbackData, oCallbackScope)</dt>
<dd>
<p>
subscribe メソッドは boomerang の <a href="#events">イベント</a> にイベントハンドラーを追加します。4つのパラメーターを受け付けます。
</p>
<h3>パラメーター:</h3>
  <dl>
  <dt>sEvent</dt>
  <dd>イベント名。<em>page_ready</em> 、<em>page_unload</em> 、<em>before_beacon</em> のうちのいずれかを指定します。</dd>

  <dt>fCallbackFn</dt>
  <dd>このイベントが発生したときに呼び出されるコールバック関数への参照。関数の記述は次のようにします:
  <pre>function(oEventData, oCallbackData);</pre>
  </dd>

  <dt>oCallbackData</dt>
  <dd><strong>[オプション]</strong> コールバック関数に2番目のパラメーターとして渡されるオブジェクト</dd>

  <dt>oCallbackScope</dt>
  <dd><strong>[オプション]</strong> もしこのオブジェクトが指定されていればコールバック関数はこのオブジェクトのメソッドとして呼び出され、コールバック関数の内部での全ての <code>this</code> への参照は oCallbackScope を参照します。</dd>
  </dl>
<p>
<code>before_beacon</code> はビーコンが発生する前に何かしたい場合に便利ですが、<code>page_ready</code> と <code>page_unload</code> イベントはほとんどのプラグインで役立ちます。さらに詳しい内容は <a href="#events">イベント</a> のセクションをご覧ください。
</p>
<h3>返り値</h3>
<p>
<code>BOOMR</code> オブジェクトへの参照。メソッドチェーンをサポートします。
</p>
</dd>

<dt>addVar(sName, sValue) または addVar(oVars)</dt>
<dd>
<p>
ビーコンに一つ以上のパラメーターを追加します。このメソッドはビーコンにパラメーターを追加したいプラグインによって使用されますが、ページの開発者が現在のリクエストにタグをつけるために使う場合もあるかもしれません。
</p>
<h3>例:</h3>
<p>
<code>addVar()</code> を使用した例は <a href="../howtos/howto-5.html">使用方法 #5</a> をご覧ください。
</p>
<p>
このメソッドは key/value のペアを含んだ一つのオブジェクト、または一つ目が変数名、二つ目が値といったような二つのパラメーターと一緒に呼び出されます。全ての名前は URL のクエリーストリングに使用できる文字列である必要があります。英数字とアンダースコアを推奨しますが、あなたが使いたい文字列でも構いません。値は文字列または数値である必要があります。こちらも名前と同じ制限があります。
</p>
<h3>返り値</h3>
<p>
<code>BOOMR</code> オブジェクトへの参照。メソッドチェーンをサポートします。
</p>
</dd>

<dt>removeVar(sName, ...)</dt>
<dd>
<p>
ビーコン URL から一つ以上の変数を削除します。これはセットしたパラメーターの値をリセットするプラグインで有効に使えます。また、<code>before_beacon</code> ハンドラーでも送信したビーコンを止めるために使用できます。使用方法は <a href="../howtos/howto-5.html">使用方法 #5</a> をご覧ください。
</p>
<p>
このメソッドは変数名のリストまたは変数名のリストを含んだ一つの配列のいずれかを受け取ります。
</p>
<h3>返り値</h3>
<p>
<code>BOOMR</code> オブジェクトへの参照。メソッドチェーンをサポートします。
</p>
</dd>

<dt>sendBeacon()</dt>
<dd>
<p>
ビーコンを送信するために boomerang へリクエストを送ります。boomerang はこのリクエストを無視する場合があります。このメソッドが呼び出されると、boomerang は全てのプラグインをチェックします。もし不完全なプラグインがあれば（プラグインの <code>is_complete()</code> をチェック）、このメソッドは false を返し何もしません。全てのプラグインに問題なければ、ビーコンに送信された全ての変数と一緒に <code>before_beacon</code> イベントを発生させます。
</p>
<p>
全ての <code>before_beacon</code> ハンドラーが終了したあとに、<code>beacon_url</code> がセットされているか、ビーコンを送信するためにパラメーターが存在するかをチェックし共に問題がなければビーコンが送信されます。
</p>
<h3>返り値</h3>
<p>
<code>BOOMR</code> オブジェクトへの参照。メソッドチェーンをサポートします。
</p>
</dd>

<dt>log(sMessage, sLevel, sSource)</dt>
<dd>
<p>
設定されたロガーへ <code>sLevel</code> のレベルと一緒に <code>sMessage</code> を記録します。このメソッドは単に設定されたロガーに全てのロギング情報を渡します。設定の詳しい方法は <a href="../howtos/howto-6.html">使用方法 #6</a> をご覧ください。
</p>
<p>
大抵の場合ログレベルを設定するよりも次のメソッドを使用したほうが便利です。
</p>
<h3>返り値</h3>
<p>
なし
</p>
</dd>

<dt>debug(sMessage, sSource)</dt>
<dd>
<p>
設定されたロガーへ <code>debug</code> レベルで <code>sMessage</code> を記録します。<code>sSource</code> がセットされていると &quot;boomerang.&quot; の文字列に結合され、ログメッセージのソースとしてセットされます。このパラメーターはプラグイン名や行番号、関数名などを出力するために使用できます。
</p>
<h3>返り値</h3>
<p>
<code>BOOMR</code> オブジェクトへの参照。メソッドチェーンをサポートします。
</p>
</dd>

<dt>info(sMessage, sSource)</dt>
<dd>
<p>
設定されたロガーへ <code>info</code> レベルで <code>sMessage</code> を記録します。<code>sSource</code> がセットされていると &quot;boomerang.&quot; の文字列に結合され、ログメッセージのソースとしてセットされます。このパラメーターはプラグイン名や行番号、関数名などを出力するために使用できます。
</p>
<h3>返り値</h3>
<p>
<code>BOOMR</code> オブジェクトへの参照。メソッドチェーンをサポートします。
</p>
</dd>

<dt>warn(sMessage, sSource)</dt>
<dd>
<p>
設定されたロガーへ <code>warn</code> レベルで <code>sMessage</code> を記録します。<code>sSource</code> がセットされていると &quot;boomerang.&quot; の文字列に結合され、ログメッセージのソースとしてセットされます。このパラメーターはプラグイン名や行番号、関数名などを出力するために使用できます。
</p>
<h3>返り値</h3>
<p>
<code>BOOMR</code> オブジェクトへの参照。メソッドチェーンをサポートします。
</p>
</dd>

<dt>error(sMessage, sSource)</dt>
<dd>
<p>
設定されたロガーへ <code>error</code> レベルで <code>sMessage</code> を記録します。<code>sSource</code> がセットされていると &quot;boomerang.&quot; の文字列に結合され、ログメッセージのソースとしてセットされます。このパラメーターはプラグイン名や行番号、関数名などを出力するために使用できます。
</p>
<h3>返り値</h3>
<p>
<code>BOOMR</code> オブジェクトへの参照。メソッドチェーンをサポートします。
</p>
</dd>

</dl>

<h2 id="events">イベント</h2>

<dl class="api">
<dt>page_ready</dt>
<dd>
<p>
ユーザーがページを利用できるようになった時に発生します。デフォルトでは <code>window.onload</code> が発生した時に発生しますが、<code>autorun</code> を <code>false</code> にしている場合は <code>BOOMR.init()</code> が呼び出されたときに <code>BOOMR.page_ready()</code> によって明示的に発生させる必要があります。
</p>
<h3>コールバック</h3>
<p>
追加されるイベントデータはコールバック関数に渡されます。いくつかのデータは <code>subscribe()</code> メソッドに渡されます。
</p>
</dd>

<dt>page_unload</dt>
<dd>
<p>
ブラウザーがページを閉じる直前に発生します。<code>window.onbeforeunload</code> が発生した時に発生します（Opera では <code>onunload</code>）。
</p>
<h3>コールバック</h3>
<p>
追加されるイベントデータはコールバック関数に渡されます。いくつかのデータは <code>subscribe()</code> メソッドに渡されます。
</p>
</dd>

<dt>before_beacon</dt>
<dd>
<p>
ビーコンがサーバーへ送信される直前に発生します。ビーコンのパラメーターは <code>BOOMR.removeVar()</code> を呼び出すことによってビーコンを止めるられます。
</p>
<h3>コールバック</h3>
<p>
コールバック関数は二つのパラメーターと一緒に呼び出されます。最初のパラメーターはビーコンに追加される全てのパラメーターを含んだオブジェクトになります。二つ目のパラメーターは <code>subscribe()</code> メソッドに渡されたコールバックデータのオブジェクトになります。もしコールバック関数が boomerang から全てのパラメーターを削除した場合、ビーコンは送信されません。
</p>
</dd>

</dl>

<h2 id="beacon">ビーコンパラメーター</h2>
<p>
独自のプラグインがない場合、boomerang はビーコンを通して次のパラメーターを送ります:
</p>
<dl>
<dt>v</dt>
<dd>使用している boomerang ライブラリーのバージョン。</dd>
<dt>u</dt>
<dd>ビーコンを送るページの URL 。</dd>
</dl>

<p>
プラグインによってはそれぞれのプラグインの API ドキュメントに記述されている独自のパラメーターを追加するかもしれません。
</p>

<p class="perma-link">
最新のソースコードとドキュメントは <a href="http://github.com/lognormal/boomerang/">github.com/lognormal/boomerang</a> に公開されています。
</p>

</body>
</html>
<!--
    Copyright (c) 2011, Yahoo! Inc.  All rights reserved.
    Copyrights licensed under the BSD License. See the accompanying LICENSE.txt file for terms.
-->
